{/* Copyright 2020 Adobe. All rights reserved.
This file is licensed to you under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License. You may obtain a copy
of the License at http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under
the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
OF ANY KIND, either express or implied. See the License for the specific language
governing permissions and limitations under the License. */}

import {Layout} from '@react-spectrum/docs';
export default Layout;

import docs from 'docs:@react-spectrum/checkbox';
import packageData from '@react-spectrum/checkbox/package.json';
import {HeaderInfo, PropTable, PageDescription} from '@react-spectrum/docs';

```jsx import
 import {Checkbox} from '@react-spectrum/checkbox';
 import {View} from '@react-spectrum/view';
 import {Flex} from '@react-spectrum/layout';
 ```

---
category: Forms
keywords: [input]
---

# Checkbox

<PageDescription>{docs.exports.Checkbox.description}</PageDescription>

<HeaderInfo
 packageData={packageData}
 componentNames={['Checkbox']}
 sourceData={[
 {type: 'Spectrum', url: 'https://spectrum.adobe.com/page/checkbox/'}
 ]}
 since="3.0.0" />

## Example

```tsx example
<Checkbox>Unsubscribe</Checkbox>
```

## Content

Checkboxes accept children, which are rendered as the label.

### Accessibility

In certain cases a visible label isn't needed. For example, a checkbox used to select a table row.
If a visible label isn't specified, an `aria-label` must be provided to the Checkbox for accessibility.
If the field is labeled by a separate element, an `aria-labelledby` prop must be provided using the id of the labeling element instead.

### Internationalization

To internationalize a Checkbox, a localized label should be passed to the `children` or `aria-label` prop.
For languages that are read right-to-left (e.g. Hebrew and Arabic), the layout of the checkbox is automatically flipped.

## Value

Checkboxes are not selected by default. The `defaultSelected` prop can be used to set the default state (uncontrolled).
Alternatively, the `isSelected` prop can be used to make the selected state controlled. See React's documentation on [uncontrolled components](https://reactjs.org/docs/uncontrolled-components.html) for more info.

```tsx example
function Example() {
  let [selected, setSelected] = React.useState(true);

  return (
    <Flex direction="row">
      <Checkbox defaultSelected>Subscribe (uncontrolled)</Checkbox>
      <Checkbox isSelected={selected} onChange={setSelected}>Subscribe (controlled)</Checkbox>
    </Flex>
  );
}
```

### Indeterminate
[View guidelines](https://spectrum.adobe.com/page/checkbox/#Mixed-value)

A Checkbox can be in an indeterminate state, controlled using the `isIndeterminate` prop.
This overrides the appearance of the Checkbox, whether selection is controlled or uncontrolled.
The Checkbox will visually remain indeterminate until the `isIndeterminate` prop is set to false, regardless of user interaction.

```tsx example
<Checkbox isIndeterminate>Subscribe</Checkbox>
```

### HTML forms

Checkbox supports the `name` and `value` props for integration with HTML forms.

```tsx example
<Checkbox name="newsletter" value="subscribe">Subscribe</Checkbox>
```

## Events

Checkboxes accept a user defined `onChange` prop, triggered whenever the Checkbox is clicked.
The example below uses `onChange` to alert the user to changes in the checkbox's state.

```tsx example
function Example() {
  let [selected, setSelection] = React.useState(false);

  return (
    <Flex direction="column">
      <Checkbox isSelected={selected} onChange={setSelection}>
        Subscribe
      </Checkbox>
      <View>{`You are ${selected ? 'subscribed' : 'unsubscribed'}`}</View>
    </Flex>
  );
 }
```

## Validation

Checkboxes can display a validation state to communicate to the user if the current value is invalid.
Implement your own validation logic in your app and set the `isInvalid` prop accordingly.
The invalid state is only communicated via a color change so in order to be accessible the validation error must also be communicated in another way.
```tsx example
<Checkbox isInvalid>I accept the terms and conditions</Checkbox>
```

## Props

<PropTable component={docs.exports.Checkbox} links={docs.links} />

## Visual options

### Disabled
[View guidelines](https://spectrum.adobe.com/page/checkbox/#Disabled)

```tsx example
<Checkbox isDisabled>Subscribe</Checkbox>
```

### Emphasized
[View guidelines](https://spectrum.adobe.com/page/checkbox/#Emphasized-or-not?)

```tsx example
<Checkbox isEmphasized defaultSelected>Subscribe</Checkbox>
```
